feat: bound Merkle proof depth at verification - #695

Here's a concise PR description you can use:

───────────────────────────────────────────────────────────────────────────────────────────────

feat: bound Merkle proof depth at verification

Summary

Adds a hard upper limit on Merkle proof length at the verification entrypoint to prevent gas
exhaustion and memory overflow from adversarially crafted deep proofs.

What changed

src/merkle_helpers.rs

• MAX_PROOF_DEPTH = 32 — public constant; covers any realistic snapshot (2³² leaves) while
  capping per-call cost
• MerkleError::ProofTooDeep = 1003 — structured error returned by the helper
• verify_merkle_proof(env, leaf_hash, root, proof) — new pure helper; O(1) depth check fires
  before any SHA-256 call

src/lib.rs

• RevoraError::ProofTooDeep = 77 — frozen wire value, stable since v1
• EVENT_PROOF_REJECT_DEPTH (prf_rej_d) — event emitted when a proof is rejected so indexers can
  observe oversized-proof attempts
• pub fn verify_merkle_proof(env, caller, leaf_hash, root, proof) — read-only, auth-free
  contract entrypoint

src/test_merkle_proof_depth.rs (new, 18 tests)

• Boundary: depth exactly 32 → Ok(true); depth 33 → Err(ProofTooDeep)
• Event: prf_rej_d emitted on rejection; not emitted on valid proofs
• Integration: build_merkle_root + verify_merkle_proof round-trip

docs/merkle-proof-depth-bound.md (new)

• Rationale, API reference, error wire values, event schema, off-chain proof construction
  guide, change-compatibility table

Security

The depth check is O(1) and runs before any hashing — an adversary cannot trigger expensive
computation by submitting an oversized proof vector.

Testing

cargo test -- --test-threads=1

All 18 new tests in test_merkle_proof_depth plus the full existing suite must pass.

▸ Closes#571